Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /

Chapter 2 - Printing Extensions / Developing a Printing Extension

The Jump Table

You need to tell QuickDraw GX where (in which segment and at what offset from the beginning of that segment) to find the code for each printing message that you are overriding. You do this by defining an assembly-language jump table. The contents
of the file backwash.a, which defines the jump table for the background picture printing extension, are shown in the QuickDraw GX sample code.

The jump table links the appropriate override function into your code and provides
a jump statement to invoke that function. The override resource tells QuickDraw GX where to look (at which offset) in the jump table to find the jump statement for a specific printing message name. In this way, QuickDraw GX knows which of your override functions to call to respond to the messages in which you are interested.

You define a jump table with one jump (JMP) statement for each message that you override. You also define an override resource that specifies the offset in that jump
table for each message. The jump table and override resource must be coordinated. QuickDraw GX dispatches a printing message to your extension by jumping to the routine whose location is specified in the appropriate location in the jump table.
The override resource is described in the section "The Override ('over') Resource" beginning on page 6-13 in the chapter "Printing Resources."

For example, the background picture printing extension overrides several printing messages, as shown in Table 2-2.

Table 2-2 Printing messages overridden by the background picture printing extension

Message	Why you override
GXInitialize	To set up the environment so that the extension can use predefined global values
GXShutDown	To free the storage that was allocated by the GXInitialize message override
GXJobPrintDialog	To add a panel to the Print dialog box so the user can select the background picture filename and intensity
GXHandlePanelEvent	To handle events that occur in the panel
GXCreateSpoolFile	To add the background picture to the spool file
GXDespoolPage	To draw the background picture on each page as it is despooled
GXCloseSpoolFile	To free the storage allocated for the background picture shape

The override resource for the background picture printing extension has to include
an entry for each of these printing messages, and the jump table has to include a
jump statement for each. Listing 2-1 shows the override resource definition from the backwash.r file. You can read about each of the printing messages in the chapter "Printing Messages" in this book.

Listing 2-1 The override resource for the background picture printing extension

resource gxOverrideType (gxExtensionUniversalOverrideID,sysHeap,
                                                      purgeable)
{
   {
   gxInitialize,        0, 4,
   gxShutDown,          0, 8,
   gxJobPrintDialog, '  0, 12,
   gxHandlePanelEvent,  0, 16,
   gxCreateSpoolFile,   0, 20,
   gxDespoolPage,       0, 24,
   gxCloseSpoolFile,    0, 28
   };
};

The name of each message is followed by the ID of the extension's code segment in which its code resides and the byte offset of its jump statement in the jump table. QuickDraw GX reserves the first 4 bytes for its own use, which makes 4 the first offset that you can use. These 4 bytes are used by QuickDraw GX to maintain an owner count and must be set to 0 in the jump table.

You implement the jump table as an assembly-language program that contains a jump statement for each override function. You need to list the jump statements with exactly the same offsets as you listed for the message names in your override resource; otherwise, QuickDraw GX will invoke the wrong function in response to a message. Listing 2-2 shows the jump table for the background picture printing extension.

Listing 2-2 The jump table for the background picture printing extension

   EXPORT EntryPoint
   IMPORT BWInitialize
   IMPORT BWShutDown
   IMPORT BWJobPrintDialog
   IMPORT BWHandlePanelEvent
   IMPORT BWCreateSpoolFile
   IMPORT BWDespoolPage
   IMPORT BWCloseSpoolFile
EntryPoint  PROC                 ; main entry point

   DC.L     0                    ; used by QuickDraw GX

   JMP      BWInitialize         ; override for GXInitialize
   JMP      BWShutDown           ; override for GXShutDown
   JMP      BWJobPrintDialog     ; override for GXJobPrintDialog
   JMP      BWHandlePanelEvent   ; override for GXHandlePanelEvent
   JMP      BWCreateSpoolFile    ; override for GXCreateSpoolFile
   JMP      BWDespoolPage        ; override for GXDespoolPage
   JMP      BWCloseSpoolFile     ; override for GXCloseSpoolFile

   ENDPROC

END

Note

The code shown in Listing 2-2 is for the MPW environment. If you are programming in a different development environment, you might need to use different assembler directives. You must, however, be certain to include the initial 4 bytes (set to 0) and each JMP statement.

The EXPORT statement at the beginning makes the jump table public. The IMPORT statements make it possible for your assembly-language program to reference the C language functions performing your message overrides and to provide correct linkage to those functions.

The name of each override function provided by the background picture printing extension is prefixed with BW to differentiate it from other overrides of the same message. This means that the extension's override of the GXInitialize message
is named BWInitialize, its override of the GXDespoolPage message is named BWDespoolPage, and so on.

Because QuickDraw GX uses the first 4 bytes in the jump table to store the owner count value, the first statement (DC.L) must be included. These bytes must all have the value 0 in them.

You must include one JMP statement for each message that you override. You can choose to intersperse the IMPORT and JMP statements as shown in Listing 3-2 on page 3-15 in the chapter "Printer Drivers," or you can place all of the IMPORT statements together, followed by all of the JMP statements, as is shown in Listing 2-2.

IMPORTANT

Always coordinate the entries in your override resources with the entries in your jump table. If they are not aligned, the wrong code will be executed to override a message. The offset that you specify in the resource for each message must match the offset of the corresponding override function in your jump table. You must also include 4 bytes with zero values at the beginning of your jump table.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help